COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	%Start Part 1 of 8 functi.tex
C00029 ENDMK
C⊗;
%Start Part 1 of 8 functi.tex
\input macros
\draftremark{\hbox{\vbox{\hbox{\prmeleven 88-003}\hbox{\prmeleven Draft distributed to X3J13 March 1988}}}}
\def\bookline{\CLOS\  Specification}
\def\chapline{Functions in the Programmer Interface}

\beginChapter 2.{Common Lisp Object System Specification}%
{Functions in the Programmer Interface}{Functions in the Programmer Interface}

Authors: Daniel G. Bobrow, Linda G. DeMichiel, Richard P.
Gabriel,\hfil\break Sonya E. Keene, Gregor Kiczales, and David A.
Moon.

{\ifdraft Draft Dated: June 15, 1988\hfil\break\fi}
All Rights Reserved

The distribution and publication of this document are not restricted.
In order to preserve the integrity of the specification, any
publication or distribution must reproduce this document in its
entirety, preserve its formatting, and include this title page.

For information about obtaining the sources for this document, send
an Internet message to 
common-lisp-object-system-specification-request@sail.stanford.edu.

The authors wish to thank Patrick Dussud, Kenneth Kahn,
Jim Kempf,\hfil\break Larry Masinter, Mark Stefik,
Daniel L. Weinreb, and Jon L White\hfil\break
for their contributions to this document.

\vskip 2pc
At the X3J13 meeting on June 15, 1988, the following motion was
adopted:

``The X3J13 Committee hereby accepts chapters 1 and 2
of the Common Lisp Object System, as defined in document
88-002R, for inclusion in the Common Lisp language being
specified by this committee. Subsequent changes will be handled
through the usual editorial and cleanup processes.''

\endTitlePage

\beginSection{Introduction}

This chapter describes the functions, macros, special forms, and
generic functions provided by the \CLOS\ Programmer Interface.  The
Programmer Interface comprises the functions and macros that are
sufficient for writing most object-oriented programs.

This chapter is reference material that requires an understanding of
the basic concepts of the Common Lisp Object System.  The functions
are arranged in alphabetical order for convenient reference.

The description of each function, macro, special form,
and generic function includes its purpose, its syntax, the
semantics of its arguments and returned values, and often an example
and cross-references to related functions.

The syntax description for a function, macro, or special form
describes its parameters. The following is an example of the format for
the syntax description of a function:

\label Syntax:

\Defgen {F} {{\it x\/} {\it y\/} {\opt} {\it z\/} \key {\it k\/}}

\noindent This description indicates that the generic function {\bf F} 
has two required parameters, {\it x\/} and {\it y}.  In addition,
there is an optional parameter {\it z\/} and a keyword parameter {\it
k}.

The generic functions described in this chapter are all standard
generic functions.  They all use standard method combination.

The description of a generic function includes descriptions of the
methods that are defined on that generic function by the \CLOS.  A
{\bit method signature\/} is used to describe the parameters and
parameter specializers for each method. The following is an example of the
format for a method signature:

\label Method Signature:

\Defmeth {F} {({\it x\/} {\it class}) ({\it y\/} t) \&optional {\it z\/} \&key {\it k\/}}

\noindent This signature indicates that this method on the generic function
{\bf F} has two required parameters, {\it x\/}, which must be an
instance of the class {\it class}, and {\it y}, which can be any
object. In addition, there is an optional parameter {\it z\/} and a
keyword parameter {\it k}.  This signature also indicates that this
method on {\bf F} is a primary method and has no qualifiers.

The syntax description for a generic function describes the
lambda-list of the generic function itself, while the method
signatures describe the lambda-lists of the defined methods.

Any implementation of the \CLOS\ is allowed to provide additional methods
on the generic functions described in this chapter.

\vfill\eject
It is useful to categorize the functions and macros according to their
role in this standard:

\Vskip 2pc!
\beginlist
\item{\bull}
{Tools used for simple object-oriented programming}

These tools allow for defining new classes, methods, and generic 
functions, and for making instances.   Some tools used within
method bodies are also listed here.   Some of the macros listed here have 
a corresponding function that performs the same task at a lower level of
abstraction. 

{\bf call-next-method}\hfil\break
{\bf change-class}\hfil\break
{\bf defclass}\hfil\break
{\bf defgeneric}\hfil\break
{\bf defmethod}\hfil\break
{\bf generic-flet}\hfil\break
{\bf generic-function}\hfil\break
{\bf generic-labels}\hfil\break
{\bf initialize-instance}\hfil\break
{\bf make-instance}\hfil\break
{\bf next-method-p}\hfil\break
{\bf slot-boundp}\hfil\break
{\bf slot-value}\hfil\break
{\bf with-accessors}\hfil\break
{\bf with-added-methods}\hfil\break
{\bf with-slots}


\item{\bull}
{Functions underlying the commonly used macros}

{\bf add-method}\hfil\break
{\bf class-name}\hfil\break
{\bf compute-applicable-methods}\hfil\break
{\bf ensure-generic-function}\hfil\break
{\bf find-class}\hfil\break
{\bf find-method}\hfil\break
{\bf function-keywords}\hfil\break
{\bf make-instances-obsolete}\hfil\break
{\bf no-applicable-method}\hfil\break
{\bf no-next-method}\hfil\break
{\bf reinitialize-instance}\hfil\break
{\bf remove-method}\hfil\break
{\bf shared-initialize}\hfil\break
{\bf slot-exists-p}\hfil\break
{\bf slot-makunbound}\hfil\break
{\bf slot-missing}\hfil\break
{\bf slot-unbound}\hfil\break
{\bf update-instance-for-different-class}\hfil\break
{\bf update-instance-for-redefined-class}

\item{\bull}
{Tools for declarative method combination}

{\bf call-method}\hfil\break
{\bf define-method-combination}\hfil\break
{\bf invalid-method-error}\hfil\break 
{\bf method-combination-error}\hfil\break
{\bf method-qualifiers}

\item{\bull}
{General Common Lisp support tools}

{\bf class-of}\hfil\break
{\bf describe}\hfil\break
{\bf documentation}\hfil\break
{\bf print-object}\hfil\break 
{\bf symbol-macrolet}

\endlist

\vfill
\endSection%{Introduction}

\beginSection{Notation}

This specification uses an extended Backus Normal Form (BNF) to
describe the syntax of the \OS.  This section discusses the syntax of
BNF expressions.  The primary extension used is the following:

$$\lbrack\!\lbrack\, O\,\rbrack\!\rbrack$$

An expression of this form will appear whenever a list of elements is
to be spliced into a larger structure and the elements can appear in
any order. The symbol $O$ represents a description of the syntax of
some number of syntactic elements to be spliced; that description must
be of the form

$$O\sub 1\ \vert\ \ldots\ \vert\ O\sub N$$

\noindent where each $O\sub i$ can be either of the form $S$ or of
the form $S{\rm *}$.  The expression $\lbrack\!\lbrack
O\,\rbrack\!\rbrack$ means that a list of the form

$$(O\sub{i\sub 1}\ldots O\sub{i\sub j})\quad 1\leq j$$

\noindent is spliced into the enclosing expression, such that if $n \neq m$
and $1\leq n,m\leq j$,
then either $O\sub{i\sub n}\neq O\sub{i\sub m}$
or $O\sub{i\sub n} = O\sub{i\sub m} = Q\sub{k}$, where for some 
$1\leq k \leq N$, $O\sub{k}$ is of the form $Q\sub{k}{\rm *}$.

For example, the expression

$$(\hbox{{\tt x}}\ {\lbrack\!\lbrack}\,\hbox{{\tt A}}\ 
 \vert\ \hbox{{\tt B}}{\rm *}\ \vert\ \hbox{{\tt C}}\,
  {\rbrack\!\rbrack}\ \hbox{{\tt y}})$$

\noindent means that at most one {\tt A}, any number of {\tt B}'s, and
at most one {\tt C} can occur in any order.
It is a description of any of these:

\screen!
(x y)
(x B A C y)
(x A B B B B B C y)
(x C B A B B B y)
\endscreen!

\noindent but not any of these:

\screen!
(x B B A A C C y)
(x C B C y)
\endscreen!

\noindent In the first case, both {\tt A} and {\tt C} appear too often,
and in the second case {\tt C} appears too often.

\vfill\eject
A simple indirection extension is introduced in order to make this
new syntax more readable:

$$\downarrow\!O$$

\noindent If $O$ is a non-terminal symbol, the right-hand side
of its definition is substituted for the entire expression 
$\downarrow\negthinspace O$. For example, the following BNF is equivalent to
the BNF in the previous example:

$$(\hbox{{\tt x}}\ {\lbrack\!\lbrack}\downarrow\!O\,
{\rbrack\!\rbrack}\ \hbox{{\tt y}})$$
$$O::= \hbox{{\tt A}}\  \vert\ \hbox{{\tt B}}{\rm *}\ \vert\ \hbox{{\tt C}}$$

\endSection




\begincom{add-method}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf add-method} adds a method to a generic
function.  It destructively modifies the generic function and returns
the modified generic function as its result.

\label Syntax:

\Defgen {add-method} {generic-function method}

\label Method Signatures:

\Defmeth {add-method} {\vtop{\hbox{({\it generic-function\/} standard-generic-function)}
\hbox{({\it method\/} method)}}}

\label Arguments:

The {\it generic-function\/} argument is a generic function
object.

The {\it method\/} argument is a method object.  The lambda-list of
the method function must be congruent with the lambda-list of the
generic function, or an error is signaled.

\label Values:

The modified generic function is returned.  The result of {\bf add-method} 
is {\bf eq} to the {\it generic-function\/} argument.

\label Remarks:

If the given method agrees with an existing method of the generic
function on parameter specializers and qualifiers, the existing method
is replaced.  See the section ``Agreement on Parameter Specializers and
Qualifiers'' for a definition of agreement in this context.

If the method object is a method object of another generic function,
an error is signaled.

\label See Also:

``Agreement on Parameter Specializers and Qualifiers''

{\bf defmethod

defgeneric

find-method

remove-method}

\endcom


\begincom{call-method}\ftype{Macro}

\label Purpose:

The macro {\bf call-method} is used in method combination.  It hides
the implementation-dependent details of how methods are called. The
macro {\bf call-method} has lexical scope and can only be used within
an effective method form.

The macro {\bf call-method} invokes the specified method, supplying it
with arguments and with definitions for {\bf call-next-method} and for
{\bf next-method-p}.  The arguments are the arguments that were
supplied to the effective method form containing the invocation of
{\bf call-method}.  The definitions of {\bf call-next-method} and {\bf
next-method-p} rely on the list of method objects given as the second
argument to {\bf call-method}.

The {\bf call-next-method} function available to the method that
is the first subform will call the first method in the list that
is the second subform.  The {\bf call-next-method} function
available in that method, in turn, will call the second
method in the list that is the second subform, and so on, until
the list of next methods is exhausted.

\label Syntax:

\Defmac {call-method} {method next-method-list}

\label Arguments:

The {\it method\/} argument is a method object; the {\it
next-method-list\/} argument is a list of method objects.

A list whose first element is the symbol {\bf make-method} and whose
second element is a Lisp form can be used instead of a method object
as the first subform of {\bf call-method} or as an element of the
second subform of {\bf call-method}.  Such a list specifies a method
object whose method function has a body that is the given form.

\label Values:

The result of {\bf call-method} is the value or values returned by
the method invocation.

\label See Also: 

{\bf call-next-method}

{\bf define-method-combination}

{\bf next-method-p}

\endcom


\begincom{call-next-method}\ftype{Function}

\label Purpose:

The function {\bf call-next-method} can be used within the body of a
method defined by a method-defining form to call the next method.

The function {\bf call-next-method} returns the value or values
returned by the method it calls.  If there is no next method, 
the generic function {\bf no-next-method} is called.

The type of method combination used determines which 
methods can invoke {\bf call-next-method}.  The standard method
combination type allows {\bf call-next-method} to be used within primary
methods and {\bf :around} methods.  The standard method combination
type defines the next method as follows:

\beginlist
\item{\bull}
If {\bf call-next-method} is used in an {\bf :around} method,
the next method is the next most specific {\bf :around} method, if one is
applicable.

\item{\bull}
If there are no {\bf :around} methods at all or if {\bf
call-next-method} is called by the least specific {\bf :around}
method,  other methods are called as follows:

\itemitem{--} All the {\bf :before} methods are called, in
most-specific-first order.  The function {\bf call-next-method}
cannot be used in {\bf :before} methods.

\itemitem{--} 
The most specific primary method is called.  Inside the body of a
primary method, {\bf call-next-method} may be used to pass control to
the next most specific primary method.  The generic function {\bf
no-next-method} is called if {\bf call-next-method} is used and there
are no more primary methods.

\itemitem{--} All the {\bf :after} methods are called in
most-specific-last order.  The function {\bf call-next-method}
cannot be used in {\bf :after} methods.

\endlist

For further discussion of {\bf call-next-method}, see the sections
``Standard Method Combination'' and ``Built-in Method Combination
Types.''

\label Syntax:

\Defun {call-next-method} {{\rest} args}

\label Arguments:

When {\bf call-next-method} is called with no arguments, it passes the
current method's original arguments to the next method.  Neither
argument defaulting, nor using {\bf setq}, nor rebinding variables
with the same names as parameters of the method affects the values
{\bf call-next-method} passes to the method it calls.

\vfill\eject
When {\bf call-next-method} is called with arguments, the next method
is called with those arguments.  When providing arguments to {\bf
call-next-method}, the following rule must be satisfied or an error is
signaled: The ordered set of methods applicable for a changed set of
arguments for {\bf call-next-method} must be the same as the ordered set of
applicable methods for the original arguments to the generic function.
Optimizations of the error checking are possible, but they must 
not change the semantics of {\bf call-next-method}.

If {\bf call-next-method} is called with arguments but omits
optional arguments, the next method called defaults those arguments.


\label Values:

The function {\bf call-next-method} returns the value or values
returned by the method it calls.  

\label Remarks:

Further computation is possible after {\bf call-next-method} returns.

The function {\bf call-next-method} has lexical scope and indefinite extent.

For generic functions using a type of method combination defined by
the short form of {\bf define-method-combination}, {\bf
call-next-method} can be used in {\bf :around} methods only.

The function {\bf next-method-p} can be used to test whether there is
a next method.

If {\bf call-next-method} is used in methods that do not support it,
an error is signaled.

\label See Also:

``Method Selection and Combination''

``Standard Method Combination'' 

``Built-in Method Combination Types''

{\bf define-method-combination}

{\bf next-method-p}

{\bf no-next-method}

\endcom




\begincom{change-class}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf change-class} changes the class of an
instance to a new class.  It destructively modifies and returns the
instance.

If in the old class there is any slot of the same name as a local
slot in the new class, the value of that slot is retained.  This
means that if the slot has a value, the value returned by {\bf
slot-value} after {\bf change-class} is invoked is {\bf eql} to the
value returned by {\bf slot-value} before {\bf change-class} is
invoked.  Similarly, if the slot was unbound, it remains
unbound.  The other slots are initialized as described in the
section ``Changing the Class of an Instance.''

\label Syntax:

\Defgen {change-class} {instance new-class}

\label Method Signatures:

%End part 1 of 8 functi.tex